What versioning strategy would you use so that switching to a new embedding model doesn't silently corrupt search quality for existing data?

The strategy is to treat the embedding model as a versioned property of the collection, not as a runtime detail. When you switch models, you create a new collection (or a new named vector within the same collection) with the new model's dimension and metric, and you dual-write new content to both the old and the new collections during the migration. You backfill the old collection's content into the new collection by re-embedding it with the new model, and you track progress so you know when the backfill is complete. Only when the new collection is fully populated and validated do you cut over the query path to it, typically by moving an alias. The old collection remains available as a rollback target until the new one has been stable for a defined period. This avoids the two failure modes of an in-place migration: mixing old and new vectors in the same collection, which produces a mix of representations that no query can rank correctly, and cutting over before the backfill is complete, which silently returns incomplete results.

The mechanism that makes this safe is that the old and new collections are separate vector spaces, and the query path always uses exactly one of them. During the migration, new writes go to both, and old data is backfilled into the new collection. If the backfill is slow, the old collection continues to serve queries correctly (it has all the data, just in the old space), and the new collection is incomplete but not yet used for queries. The migration state is therefore always consistent from the query path's perspective: it either uses the old collection (complete, old space) or the new collection (complete, new space), never a mix. The cutover is a metadata operation (moving an alias) and can be rolled back by moving the alias back. The validation before cutover compares recall on the new collection against a held-out query set, and compares the new collection's results with the old collection's results on a sample of queries to ensure that quality has not regressed. This is the standard pattern for any schema or model change that cannot be done in place.

The trade-off is between the cost of running two collections during the migration and the safety of never mixing vector spaces. The dual-write and backfill require extra storage and compute, and the migration takes time proportional to the corpus size and the embedding throughput. The alternative - an in-place migration where you update the collection's config and re-embed - is not possible in Qdrant because the dimension and metric are immutable, but even if it were, it would be unsafe because during the migration the collection would contain a mix of old and new vectors. The common mistake is to try to run both models against the same collection by storing the model version in the payload and filtering, which does not work because the vector spaces are incompatible. The second mistake is to cut over before the backfill is complete, which silently returns incomplete results. The third mistake is to skip the validation step, so a model that is worse than the old one is deployed. The fourth mistake is to delete the old collection immediately after cutover, leaving no rollback path. Version note: the alias API and the collection creation API have been stable, but the exact shape of the alias operations and the supported named vector configurations have evolved. The named-vector alternative (adding a new vector field to an existing collection) is a newer capability and its API may differ across versions.

Version-dependent: the alias API and the collection creation API have been stable, but the exact shape of the alias operations and the support for named vectors with different dimensions have evolved. In some versions, a collection can have multiple named vectors with different dimensions and metrics, which enables an in-collection migration by adding a new named vector and gradually moving queries and writes to it. The query_points API is qdrant-client 1.10+; older clients used search(). Verify the migration capabilities on your version before planning.